The Kinetis SDK provides both HAL and Peripheral drivers for the Soundcard (SND) block of Kinetis devices. More...

Data Structures
struct	snd_state_t
	Soundcard status includes the information which the application can see. More...

struct	audio_ctrl_operation_t
	The operations of an audio controller, for example SAI, SSI and so on. More...

struct	audio_codec_operation_t
	Audio codec operation structure. More...

struct	audio_controller_t
	The definition of the audio device which may be a controller. More...

struct	audio_codec_t
	The Codec structure. More...

struct	audio_buffer_t
	Audio buffer structure. More...

struct	sound_card_t
	A sound card includes the audio controller and a Codec. More...

Macros
#define	AUDIO_CONTROLLER AUDIO_CONTROLLER_SAI
	Define audio controller sai.

#define	AUDIO_CONTROLLER_SAI 1

#define	AUDIO_CODEC AUDIO_CODEC_SGTL5000
	Define audio codec sgtl5000.

#define	AUDIO_CODEC_SGTL5000 1

#define	AUDIO_BUFFER_BLOCK_SIZE 128
	Buffer block size setting.

#define	AUDIO_BUFFER_BLOCK 2
	Buffer block number setting.

#define	AUDIO_BUFFER_SIZE (AUDIO_BUFFER_BLOCK * AUDIO_BUFFER_BLOCK_SIZE)

#define	AUDIO_TX 1
	Audio transfer direction Tx.

#define	AUDIO_RX 0
	Audio transfer direction Rx.

Typedefs
typedef sai_handler_t	ctrl_handler_t

typedef sai_user_config_t	ctrl_config_t

typedef sai_data_format_t	ctrl_data_format_t

typedef sai_callback_t	ctrl_callback_t

typedef sai_status_t	ctrl_status_t

typedef sgtl_handler_t	codec_handler_t

typedef sgtl_status_t	codec_status_t

Enumerations
enum	snd_status_t { kStatus_SND_Success = 0U, kStatus_SND_Fail = 1U, kStatus_SND_DmaFail = 2U, kStatus_SND_CtrlFail = 3U, kStatus_SND_CodecFail = 4U, kStatus_SND_BufferAllocateFail = 5U }
	Soundcard return status. More...

Functions
snd_status_t	snd_init (sound_card_t card, void ctrl_config, void *codec_config)
	Initializes the Soundcard. More...

snd_status_t	snd_deinit (sound_card_t *card)
	Deinitializes the sound card instance. More...

snd_status_t	snd_data_format_configure (sound_card_t card, ctrl_data_format_t format)
	Configures the audio data format running in the Soundcard. More...

uint32_t	snd_update_tx_status (sound_card_t *card, uint32_t len)
	Updates the status of the TX. More...

uint32_t	snd_update_rx_status (sound_card_t *card, uint32_t len)
	Updates status of the RX. More...

void	snd_get_status (snd_state_t status, sound_card_t card)
	Gets the status of the Soundcard. More...

void	snd_start_tx (sound_card_t *card)
	Starts the Soundcard TX process. More...

void	snd_start_rx (sound_card_t *card)
	Starts the Soundcard RX process. More...

static void	snd_stop_tx (sound_card_t *card)
	Stops Soundcard TX process. More...

static void	snd_stop_rx (sound_card_t *card)
	Stops the Soundcard RX process. More...

void	snd_wait_event (sound_card_t *card)
	Waits for the semaphore of the write/read data from the internal buffer. More...

Variables
audio_ctrl_operation_t	g_sai_ops

audio_codec_operation_t	g_sgtl_ops

Soundcard Driver

Overview

The Soundcard is used to handle both audio controller and audio Codec. It provides an easy way to initialize, configure and handle(read/write) the Soundcard.

Initialization

A Soundcard includes a controller and a Codec (SAI + sgtl5000). Application needs to prepare the configuration structure for SAI and SGTL5000, and then call the snd_init() to finish the initialization.

Configuration

The configuration includes the static configuration and dynamic configuration. Static configuration is configuring the SAI features. Dynamic configuration is configuring the audio data format (sample rate and bit depth).

Call diagram

To use the SAI driver, user should follow these steps:

Initialize the Soundcard by calling the snd_init() function.
Configure the audio data format information of the Soundcard by calling the snd_data_format_configure() function.
Update the status of the Soundcard after copying into/output from the buffer by calling the snd_update_status() function.
Start the TX/RX by calling the snd_start_tx() or the snd_start_rx() function.
Stop by calling the snd_stop_tx() or snd_stop_rx() functions.
Close the devices by calling the snd_deinit() function.

This is an example code to initialize and configure the SAI driver in the DMA mode:

    sound_card_t g_card;
    static audio_data_format_t *format;
    static sai_config_t tx_config;
    void snd_card_config(void)
    {
        /* SAI configuration */
        tx_config.bus_type = kSaiBusI2SLeft;
        tx_config.channel = 0;
        tx_config.slave_master = kSaiMaster;
        tx_config.sync_mode = kSaiModeAsync;
        tx_config.bclk_source = kSaiBclkSourceMclkDiv;
        tx_config.mclk_source = kSaiMclkSourceSysclk;
        tx_config.mclk_divide_enable = true;
        sai_handler_t *tx_handler = (sai_handler_t *)        mem_allocate_zero(sizeof(sai_handler_t));
        g_card.controller.handler = tx_handler;
        tx_handler->direction = AUDIO_TX;
        tx_handler->instance = 0;
        tx_handler->fifo_channel = 0;
        g_card.controller.ops = &g_sai_ops;
#if USEDMA
        g_card.controller.dma_source = kDmaRequestMux0I2S0Tx;
#endif
        sgtl_handler_t *codec_handler = (sgtl_handler_t *)        mem_allocate_zero(sizeof(sgtl_handler_t));
        g_card.codec.handler = codec_handler;
        g_card.codec.ops = &g_sgtl_ops;
    }
    // Initialize the Soundcard basically
    snd_init(&g_card);
    // Configure the audio data format for TX
    snd_data_format_configure(&g_card,format);
    // Copy data to SAI buffer
    snd_wait_event(&g_card);
    snd_get_status(&tx_status, &g_card);
    memcpy(tx_status.input_address, pData, tx_status.size);
    snd_update_tx_status(&g_card, tx_status.size);

Data Structure Documentation

struct snd_state_t

This structure is the interface between the driver and the application. The application can get the information where and when to input/output data.

Data Fields
uint32_t	size
	The size of a block.

uint32_t	empty_block
	How many blocks are empty.

uint32_t	full_block
	How many blocks are full.

uint8_t *	input_address
	The input address.

uint8_t *	output_address
	The output address.

struct audio_ctrl_operation_t

The operation includes the basic initialize, configure, send, receive and so on.

Data Fields
ctrl_status_t(*	ctrl_init )(ctrl_handler_t param, ctrl_config_t config)
	Initializes the controller. More...

ctrl_status_t(*	ctrl_deinit )(ctrl_handler_t *param)
	Deinitializes the controller. More...

ctrl_status_t(*	ctrl_config_data_format )(ctrl_handler_t param, ctrl_data_format_t format)
	Configures the audio data format. More...

void(*	ctrl_start_write )(ctrl_handler_t *param)
	Used in a start transfer or a resume transfer.

void(*	ctrl_start_read )(ctrl_handler_t *param)
	Used in a start receive or a resume receive.

void(*	ctrl_stop_write )(ctrl_handler_t *param)
	Used in the stop transfer.

void(*	ctrl_stop_read )(ctrl_handler_t *param)
	Used in the stop receive.

uint32_t(*	ctrl_send_data )(ctrl_handler_t param, uint8_t addr, uint32_t len)
	Sends data function.

uint32_t(*	ctrl_receive_data )(ctrl_handler_t param, uint8_t addr, uint32_t len)
	Receives data.

void(*	ctrl_register_callback )(ctrl_handler_t param, ctrl_callback_t callback, void callback_param)
	Registers a callback function. More...

uint32_t (	ctrl_get_fifo_address )(ctrl_handler_t *param)
	Gets the FIFO address.

Field Documentation

ctrl_status_t(* audio_ctrl_operation_t::ctrl_init)(ctrl_handler_t *param, ctrl_config_t *config)

ctrl_status_t(* audio_ctrl_operation_t::ctrl_deinit)(ctrl_handler_t *param)

ctrl_status_t(* audio_ctrl_operation_t::ctrl_config_data_format)(ctrl_handler_t *param, ctrl_data_format_t *format)

void(* audio_ctrl_operation_t::ctrl_register_callback)(ctrl_handler_t *param, ctrl_callback_t callback, void *callback_param)

struct audio_codec_operation_t

Data Fields
codec_status_t(*	codec_init )(codec_handler_t param, void config)
	Codec initialize function.

codec_status_t(*	codec_deinit )(codec_handler_t *param)
	Codec deinitialize function.

codec_status_t(*	codec_config_data_format )(codec_handler_t *param, uint32_t mclk, uint32_t sample_rate, uint8_t bits)
	Configures data format. More...

Field Documentation

codec_status_t(* audio_codec_operation_t::codec_config_data_format)(codec_handler_t *param, uint32_t mclk, uint32_t sample_rate, uint8_t bits)

struct audio_controller_t

Data Fields
void *	handler

audio_ctrl_operation_t *	ops
	Operations including the initialize, configure, etc. More...

Field Documentation

audio_ctrl_operation_t* audio_controller_t::ops

struct audio_codec_t

Data Fields
void *	handler
	Codec instance.

audio_codec_operation_t *	ops
	Operations. More...

Field Documentation

audio_codec_operation_t* audio_codec_t::ops

struct audio_buffer_t

Data Fields
uint8_t *	buff
	Buffer address.

uint8_t	blocks
	Block number of the buffer. More...

uint16_t	size
	The size of a block.

uint32_t	requested
	The request data number to transfer.

uint32_t	queued
	Data which is in buffer, but not processed. More...

uint32_t	processed
	Data which is put into the FIFO. More...

uint8_t	input_index
	Buffer input block index. More...

uint8_t	output_index
	Buffer output block index. More...

uint8_t *	input_curbuff
	Buffer input address. More...

uint8_t *	output_curbuff
	Buffer output address. More...

uint32_t	empty_block
	Empty block number. More...

uint32_t	full_block
	Full block numbers. More...

uint32_t	fifo_error
	FIFO error numbers. More...

uint32_t	buffer_error
	Buffer error numbers. More...

sync_object_t	sem
	Semaphores to control the data flow. More...

bool	first_io
	Means the first time the transfer.

Field Documentation

uint8_t audio_buffer_t::blocks

uint32_t audio_buffer_t::queued

uint32_t audio_buffer_t::processed

This is used to judge if the SAI is under run.

uint8_t audio_buffer_t::input_index

uint8_t audio_buffer_t::output_index

uint8_t* audio_buffer_t::input_curbuff

uint8_t* audio_buffer_t::output_curbuff

uint32_t audio_buffer_t::empty_block

uint32_t audio_buffer_t::full_block

uint32_t audio_buffer_t::fifo_error

uint32_t audio_buffer_t::buffer_error

sync_object_t audio_buffer_t::sem

struct sound_card_t

Data Fields
audio_controller_t	controller
	Controller.

audio_codec_t	codec
	Codec.

audio_buffer_t	buffer
	Audio buffer managed by Soundcard. More...

bool	direction
	TX or RX.

Field Documentation

audio_buffer_t sound_card_t::buffer

Enumeration Type Documentation

enum snd_status_t

Enumerator
kStatus_SND_Success	Execute successfully.
kStatus_SND_Fail	Execute fail.
kStatus_SND_DmaFail	DMA operation fail.
kStatus_SND_CtrlFail	Audio controller operation fail.
kStatus_SND_CodecFail	Audio codec operation fail.
kStatus_SND_BufferAllocateFail	Buffer allocate failure.

Function Documentation

snd_status_t snd_init	(	sound_card_t *	card,
		void *	ctrl_config,
		void *	codec_config
	)

The function initializes the controller and the Codec.

The function initializes the generic layer structure, for example the buffer and the status structure, then the function calls the initialize functions of the controller and the Codec.

Parameters

card	Soundcard pointer
ctrl_config	The configuration structure of the audio controller
codec_config	The configuration structure of the audio Codec

Returns: Return kStatus_SND_Success while the initialize success and kStatus_SND_fail if failed.

snd_status_t snd_deinit ( sound_card_t * card )

The function calls the Codec and controller deinitialization function and frees the buffer controlled by the sound card. The function should be used at the end of the application. If the playback/record is paused, you shouldn't use the function. Instead, you should use the snd_stop_tx/snd_stop_rx instead.

Parameters

card	Soundcard pointer

Returns: Return kStatus_SND_Success while the initialize success and kStatus_SND_fail if failed.

snd_status_t snd_data_format_configure	(	sound_card_t *	card,
		ctrl_data_format_t *	format
	)

This function can make the application change the data format during the run time. This function cannot be called while TCSR.TE or RCSR.RE is enabled. This function can change the sample rate, bit depth(i.e. 16-bit).

Parameters

card	Soundcard pointer
format	Data format used in the sound card

Returns: Return kStatus_SND_Success while the initialize success and kStatus_SND_fail if failed.

uint32_t snd_update_tx_status	(	sound_card_t *	card,
		uint32_t	len
	)

This function should be called after the application copied data into the buffer provided by the Soundcard. The Soundcard does not help users copy data to the internal buffer. This operation should be done by the applications. Soundcard provides an interface ,snd_get_status(), for an application to get the information about the internal buffer status, including the starting address and empty blocks and so on.

Parameters

card	Soundcard pointer
len	Data size of the data to write

Returns: The size which has been written.

uint32_t snd_update_rx_status	(	sound_card_t *	card,
		uint32_t	len
	)

This function should be called after the application copied data from the buffer provided by the Soundcard. The Soundcard does not help applications to copy data from the internal buffer. This operation should be done by applications. The Soundcard provides an interface snd_get_status() for applications to get the information about the internal buffer status, including the starting address and full blocks and so on.

Parameters

card	Soundcard pointer
len	Data size of data to read

Returns: The data size which has been read.

void snd_get_status	(	snd_state_t *	status,
		sound_card_t *	card
	)

Each time the application wants to write/read data from the internal buffer, it should call this function to get the status of the internal buffer. This function copies data to the

Parameters

status,from	the structure. The user can get the information about where to write/read data and how much data can be read/written.
card	Soundcard pointer
status	Pointer of the audio_status_t structure
card	Soundcard pointer

void snd_start_tx ( sound_card_t * card )

This function starts the TX process of the Soundcard. This function enables the DMA/interrupt request source and enables the TX and the bit clock of the TX. Note that this function can be used both in the beginning of the SAI transfer and also resume the transfer.

Parameters

card	Soundcard pointer

void snd_start_rx ( sound_card_t * card )

This function starts the RX process of the Soundcard. This function is the same as the snd_start_tx. It is used in the beginning of the Soundcard RX transfer and also resume RX.

Parameters

card	Soundcard pointer

static void snd_stop_tx ( sound_card_t * card )

inlinestatic

This function stops the transfer of the Soundcard TX. Note that this function does not close the audio controller. It disables the DMA/interrupt request source. Therefore, this function can be used to pause the audio play.

Parameters

card	Soundcard pointer

static void snd_stop_rx ( sound_card_t * card )

inlinestatic

This function is the same as the snd_stop_tx, used to stop the RX process. This function also disables the DMA/interrupt source.

Parameters

card	Soundcard pointer

void snd_wait_event ( sound_card_t * card )

Application should call this function before write/read data from the Soundcard buffer. Before application writes data to the Soundcard buffer, the buffer must have free space for the new data, or it causes data loss. This function waits for the semaphore which represents free space in the Soundcard buffer. Similarly to the reading data from the Soundcard buffer, effective data must be in the buffer. This function waits for that semaphore.

Parameters

card	Soundcard pointer

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Soundcard Driver

Overview

Initialization

Configuration

Call diagram

Data Structure Documentation

Data Fields

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Data Fields

Field Documentation

Enumeration Type Documentation

Function Documentation